home *** CD-ROM | disk | FTP | other *** search
/ Aminet 40 / Aminet 40 (2000)(Schatztruhe)[!][Dec 2000].iso / Aminet / util / sys / Dev-Handler.readme < prev    next >
Text File  |  2000-11-01  |  17KB  |  455 lines
  1. Short:    Un*x like raw device access handler plus more
  2. Author:   thor@math.tu-berlin.de (Thomas Richter)
  3. Uploader: thor@math.tu-berlin.de (Thomas Richter)
  4. Version:  40.3
  5. Type:     util/sys
  6. Requires: OS 2.04
  7.  
  8. ------------------------------------------------------------------------------
  9.  
  10. New in 40.3:
  11.  
  12.     - due to permanent trouble with the NSD specifications, NSD support
  13.       is now disabled if the NSDPatch isn't found active. This means that
  14.       the NSDPatch would be even required in case all devices in the system
  15.       would support NSD correctly. Call this a design bug of NSD.
  16.     - Added the possibility to write-protect certain dos devices. The 
  17.       devices to be write-protected are specified by the "Control" entry
  18.       in the mount list. See below for the specifications.
  19.     - Found that the 64 multiplication of the Os - which is used by this
  20.       device handler - is actually broken. Funny enough, the 68000 and
  21.       010 version is fine, the 68020 and up versions are broken, but
  22.       are worked around by the device handler itself. This workaround
  23.       broke the 68000 version. To complete the mess, the Os specifications
  24.       will now be changed to continue support for the "broken" API. This
  25.       release contains a temporary fix for the problem. Further SetPatch
  26.       releases will contain this fix as well. Please install the patch
  27.       for now, and replace it by a new version of SetPatch as soon as it
  28.       appears.
  29.  
  30. ------------------------------------------------------------------------------
  31.  
  32. New in 40.2.1:
  33.  
  34.     - included a fix for the statram.device which crashed on NSDQuery.
  35.     - included "Extract", an Amiga lookalike of the Un*x "dd" program to
  36.       copy or extract portions of files, propably sectors of a "special"
  37.       file.
  38.  
  39. ------------------------------------------------------------------------------
  40.  
  41. Purpose of this program:
  42.  
  43. The DEV-Handler allows easy access to raw sectors of an exec type device under
  44. the dos.library environment. A typical application would be to use the "copy"
  45. command to make a full backup of a floppy to a file, or to use "copy" to make
  46. a backup of the RDB of your HD.
  47.  
  48. The DEV-Handler is very powerful, but also very dangerous in the wrong hands
  49. because it modifies the device structure going down to the exec handler
  50. directly without using any kind of filing system access.
  51.  
  52. This DEV-Handler replaces various other DEV-Handlers and improves and fixes
  53. many problems of these earlier releases. Note that no original code of these
  54. versions have been used, this handler is a complete rewrite.
  55.  
  56. ------------------------------------------------------------------------------
  57.  
  58. Usage:
  59.  
  60. A file name for the DEV-Handler is either a "DOS" device name like "df0" or
  61. "DH0" in which case this "file" indicates the full partition addressed by this
  62. name. For example, "DEV:df0" is the raw, unmapped first internal floppy drive,
  63. "DEV:dh0" the first harddisk partition. The start of the file using this syntax
  64. is always the start of the partition, the length of the file the full length of
  65. the partition. Especially, this does NOT include the RDB, if there is one.
  66.  
  67. The alternative syntax addresses an exec device directly and completely,
  68. ignoring partitions. A file name using this syntax looks as follows:
  69.  
  70. DEV:device/unit/flags/bufmemtype/mask/maxtransfer
  71.  
  72. where    
  73.  
  74. device            is an exec device name, i.e. "scsi.device". This is
  75.             mandatory.
  76. unit            is the exec unit number, typically the SCSI ID. This
  77.             is mandatory. If only one argument is given, the
  78.             DEV-Handler reads the device as DOS partition name and
  79.             not as an exec name. This is a numeral.
  80. flags            exec flags for opening the device. Optionally and
  81.             defaults to zero. This is a numeral.
  82. bufmemtype        the memory type for the buffer to allocate for device
  83.             I/O. Optionally and defaults to 
  84.             MEMF_24BITDMA|MEMF_PUBLIC.
  85.             This is a numeral, or one of the following hard-coded
  86.             identifiers:
  87.  
  88.             MEMF_ANY, ANY        whatever is available, this is
  89.                         identical to MEMF_PUBLIC for
  90.                         the purpose of this handler.
  91.             MEMF_PUBLIC, PUBLIC    public (non-virtual) memory.
  92.             MEMF_CHIP, CHIP        chip memory.
  93.             MEMF_FAST, FAST        non-chip, i.e. FAST memory.
  94.             MEMF_LOCAL, LOCAL    native motherboard memory that
  95.                         does not go away on reset.
  96.             MEMF_24BITDMA, 24BITDMA    memory in the 24 bit address
  97.                         space reachable for Zorro-II
  98.                         DMA.
  99.             MEMF_ZORROII, ZORROII    a synonym for the above.
  100.  
  101.             All other values are read as numerals, hex identifiers
  102.             using the "$" or "0x" notation are allowed here as
  103.             well.
  104.             
  105.             This field fulfills the same purpose than the
  106.             BUFMEMTYPE in the mount lists.
  107.  
  108. mask            A mask used for checking whether the supplied buffer is
  109.             "proper". If "memory and not mask" is non-zero, the 
  110.             handler will fall back to single block-I/O like the FFS.
  111.  
  112.             This field has the same purpose and works in the same
  113.             way as the "MASK" entry in mountlists. 
  114.  
  115.             It is optional, the handler will compute a reasonable
  116.             mask for you using the supplied or non-supplied 
  117.             bufmemtype.
  118.  
  119.             This entry is a numeral, hex notation is accepted.
  120.  
  121. maxtransfer        The maximal amount of bytes the exec device is able to
  122.             transfer at once. Larger chunks are split into smaller
  123.             pieces at most as big as the "maxtransfer".
  124.  
  125.             This field works as the "MAXTRANSFER" entry in mount-
  126.             lists. It defaults to 32767, i.e. 32K-1. 
  127.  
  128.             This entry is a numeral, hex notation is accepted.
  129.  
  130. ------------------------------------------------------------------------------
  131.  
  132. Examples:        Note that the DEV-Handler is clearly an expert-tool,
  133.             unsophisticated playing with the DEV-Handler may easely
  134.             destroy the data-integrity of your HD!
  135.  
  136. Make a byte for byte backup of a floppy in drive 0 - known as ".adf" file:
  137.  
  138.     copy dev:df0 to Backup.adf
  139.  
  140. No need to run or use any kind of "ADF" conversion utility. 
  141.  
  142.  
  143. Restore a backup to the floppy:
  144.  
  145.     copy Backup.adf to dev:df0
  146.  
  147. Yes, it is really that simple. (-:
  148.  
  149.  
  150. Make a byte copy of the ZIP partition for future use:
  151.  
  152.     copy DEV:ZIP to Backup
  153.  
  154.  
  155. View the "RDB" block of your boot volume, connected to the scsi.device, 
  156. unit 0:
  157.  
  158.     type DEV:scsi.device/0 hex
  159.  
  160.  
  161. Make a backup of the RDB (on block #0) on the omniscsi.device, ID 0 
  162. to a backup file:
  163.  
  164.     extract dev:omniscsi.device/0 BC=1 to ram:rdb
  165.     
  166.  
  167. Extract the root block of the floppy drive in df0: to ram:out:
  168.  
  169.     extract dev:df0 IS=880 BC=1 to ram:out
  170.  
  171. Restore a previous RDB backup:
  172.  
  173.     extract ram:rdb to dev:omniscsi.device/0 BC=1
  174.  
  175. ------------------------------------------------------------------------------
  176.  
  177. Installation:
  178.  
  179. - Copy "Device-Handler" to L:
  180.  
  181. - Copy "DEV" and "DEV.info" to "Storage/DOSDrivers".
  182.  
  183. I *do not* recommend to mount DEV: automatically on startup since accidental
  184. playing with DEV: may really yield to major damage!
  185.  
  186. The mount file in this archive will write-protect the hard-disk devices DHx,
  187. where x is an arbitrary character. In case you do not want this, or want to
  188. include further devices in the write protection, edit the mount file; the
  189. list of devices to be write protected is specified in the line
  190.  
  191. Control = "PROTECT=<pattern>"
  192.  
  193. where <pattern> is an AmigaOs wild card pattern that will be matched against
  194. a DOS device name. In case of a fit, this device will not allow write access.
  195. In case you do not need this protection, just remove this line.
  196.  
  197. Examples:
  198.  
  199. Control = "PROTECT=DH?"
  200.  
  201. Protects the DHx devices, where x is an arbitrary character, i.e. DH0, DH1
  202. and so on.
  203.  
  204. Control = "PROTECT=(DH?|ZIP)"
  205.  
  206. Write protection includes the ZIP device. *NOTE THAT THIS SPECIFICATION DOES
  207. NOT INCLUDE THE TERMINATING COLON*.
  208.  
  209.  
  210. *DO NOT* remove the dummy specifications below the "Control" line. They are
  211. not required by the DEV-Handler, but by Mount to setup the "Control" entry
  212. correctly. Otherwise, there will be no protection whatsoever.
  213.  
  214.  
  215. - Copy "Extract" to C:
  216.  
  217. - Install the statram.device patch as follows:
  218.  
  219.     - make a backup of DEVS:statram.device
  220.     - spatch -oram:statram.device -pstatram.pch devs:statram.device
  221.     - copy ram:statram.device back to DEVS:
  222.  
  223. - Install the FixLongMult patch in your startup-sequence, somewhere below
  224.   SetPatch.
  225.  
  226.     - Copy FixLongMult to C:
  227.     - Open S:Startup-Sequence with an editor of your choice.
  228.     - Locate the "SetPatch" command.
  229.     - Insert a blank line below this command.
  230.     - Enter "FixLongMult" into this line.
  231.     - Save the changes.
  232.  
  233.  
  234. ------------------------------------------------------------------------------
  235.  
  236. statram.pch:
  237.  
  238.     This patch fixes a bug in the statram.device which crashes upon
  239.     receiving NSDQuery. Even though this is clearly a bug of the device,
  240.     it is a design flaw of the NSDQuery mechanism to provocate this
  241.     bug by an uncarefully designed interface.
  242.     This fix DOES NOT make statram.device NSD compatible (why?), it just
  243.     fixes the crash and nothing more.
  244.  
  245. ------------------------------------------------------------------------------
  246.  
  247. FixLongMult:
  248.  
  249.     Fixes a bug in UMult64 and SMult64 for the 68000, 68010 and 68060.
  250.     Does nothing for 68020, 68030 and 68040. In fact, it "corrects"
  251.     the 68000, 010, 060 versions to use the same "wrong" syntax than the
  252.     68020,030,040 versions. In fact, this "wrong" syntax is now the 
  253.     official syntax.
  254.  
  255.     *Without this fix, the DEV-Handler and other programs will not run
  256.     correctly on the 68000, 68010 and possibly the 68060.*
  257.  
  258.     This fix should be replaced by a new SetPatch release as soon as it
  259.     appears.
  260.  
  261. ------------------------------------------------------------------------------
  262.  
  263. Extract:
  264.  
  265.     This is a Un*x like dd program for copying portions of a file. It is
  266.     in fact unrelated to the DEV: handler, but might be a useful tool
  267.     for purposes the DEV: handler has been written for.
  268.     
  269. Synopsis:
  270.  
  271. Extract FROM=IF,TO=OF,BLOCKSIZE=IBS/N,DESTBLOCKSIZE=OBS/N,SEEK=IS/N,
  272.     DESTSEEK=OS/N,COUNT=BC/N/A: 
  273.  
  274. FROM=IF:        Input file, the data source. If this parameter is
  275.             missing, Extract will run as a "filter" and will read
  276.             from the standard input.
  277.  
  278. TO=OF:            Output file, the data destination. If this file does
  279.             not exist, it is created, but an existing file will
  280.             not be deleted, but modified.
  281.             If this parameter is missing, Extract will run as a
  282.             "filter" and will write to the standard output.
  283.  
  284.             Useful for "pipeing" the output to "type" to make
  285.             single blocks of a harddisk readable.
  286.  
  287. BLOCKSIZE=IBS:        Input block size in bytes. "Extract" will always read
  288.             single blocks of this (fixed) size from the input,
  289.             and the "COUNT" field measures the data length in
  290.             multiplies of this size.
  291.             Neither the FFS nor DEV: require reading with fixed
  292.             block sizes, but it might be useful for some
  293.             purposes.
  294.  
  295.             If no block size is given, this parameter defaults to
  296.             512 bytes.
  297.  
  298.             NOTE THAT Extract IS NOT ABLE TO DETERMINATE THE TRUE
  299.             BLOCK SIZE OF A "DEV:" FILE IT IS TALKING TO. Extract
  300.             is unrelated to DEV: at all.
  301.  
  302.             Hence, in case your HD uses 2048 bytes blocks, you
  303.             MUST specify a IBS of 2048.
  304.  
  305. DESTBLOCKSIZE=OBS    Output block size in bytes. "Extract" will always
  306.             write single blocks of this size to the output, one at
  307.             a time.
  308.         
  309.             If no block size is given, this parameter defaults to
  310.             512 bytes.
  311.  
  312.             READ THE WARNING ABOVE CONCERNING THE BLOCK SIZE.
  313.  
  314.             Extract is able to handle situations where the IBS is
  315.             different from the OBS, or not even a multiple of the
  316.             IBS. However, if this happens, the last block written
  317.             is no longer guaranteed to be OBS bytes long. It might
  318.             be shorter. In case the destination stream cannot
  319.             handle this situation, it is up to you to avoid this.
  320.  
  321. SEEK=IS            Input seek. The number of blocks to be skipped in the
  322.             input file before starting reading. The number of
  323.             bytes to be skipped is therefore IS*IBS.
  324.  
  325.             Extract and DEV: are able to handle situations where
  326.             IS*IBS is larger than 4GB by performing multiple Seeks
  327.             to get to the desired file position. 
  328.  
  329.             The FFS 45.xx *should* support this correctly, too,
  330.             but maybe the handler you are using is not! 
  331.             Be aware of this problem.
  332.  
  333. DESTSEEK=OS        Output seek. The number of blocks, measured in OBS,
  334.             to be skipped in the output stream before writing.
  335.  
  336.             See also the warnings concerning IS above.
  337.  
  338. COUNT=BC        Block count. The number of blocks, measured in IBS,
  339.             to be read from the source. The same number of bytes
  340.             is then written back to the output file, but the
  341.             number of output blocks might be different if OBS is
  342.             not equal to IBS.
  343.  
  344. ------------------------------------------------------------------------------
  345.  
  346. Improvements over the 37.xx releases (note that this is a re-design):
  347.  
  348. - Keeps care about popular device bugs including the standard-workarounds the
  349.   FFS offers as well, including a MASK, MAXTRANSFER and BUFMEMTYPE.
  350. - Allows concurrent reading and writing to the same stream.
  351. - Implements ACTION_SEEK, i.e. seeking in device streams is possible.
  352. - Automatically turns off the drive motors after a fixed delay like the FFS.
  353. - Handles large devices correctly using the TD64 and/or the TD64 standard.
  354. - Handles errors on Read/Write correctly, unlike the V37 edition.
  355.  
  356. ------------------------------------------------------------------------------
  357.  
  358.                          The THOR-Software Licence (v2, 24th June 1998)
  359.  
  360.  
  361. This License applies to the computer programs known as "Device-Handler" and
  362. "Extract". The "Program", below, refers to such program. The "Archive" refers
  363. to the the original and unmodified package of distribution, as prepared by the 
  364. author of the Program. Each licensee is addressed as "you".
  365.  
  366.  
  367.  
  368. The Program and the data in the archive are freely distributable
  369. under the restrictions stated below, but are also Copyright (c)
  370. Thomas Richter.
  371.  
  372. Distribution of the Program, the Archive and the data in the Archive by a
  373. commercial organization without written permission from the author to any
  374. third party is prohibited if any payment is made in connection with such
  375. distribution, whether directly (as in payment for a copy of the Program) or
  376. indirectly (as in payment for some service related to the Program, or
  377. payment for some product or service that includes a copy of the Program
  378. "without charge"; these are only examples, and not an exhaustive enumeration
  379. of prohibited activities).
  380.  
  381.  
  382. However, the following methods of distribution
  383. involving payment shall not in and of themselves be a violation of this
  384. restriction:
  385.  
  386.  
  387. (i) Posting the Program on a public access information storage and
  388. retrieval service for which a fee is received for retrieving information
  389. (such as an on-line service), provided that the fee is not
  390. content-dependent (i.e., the fee would be the same for retrieving the same
  391. volume of information consisting of random data).
  392.  
  393.  
  394. (ii) Distributing the Program on a CD-ROM, provided that
  395.  
  396. a) the Archive is reproduced entirely and verbatim on such CD-ROM, including
  397. especially this licence agreement;
  398.  
  399. b) the CD-ROM is made available to the public for a nominal fee only,
  400.  
  401. c) a copy of the CD is made available to the author for free except for
  402. shipment costs, and
  403.  
  404. d) provided further that all information on such CD-ROM is redistributable
  405. for non-commercial purposes without charge.
  406.  
  407.  
  408. Redistribution of a modified version of the Archive, the Program or the
  409. contents of the Archive is prohibited in any way, by any organization,
  410. regardless whether commercial or non-commercial. Everything must be kept
  411. together, in original and unmodified form.
  412.  
  413.  
  414.  
  415.  
  416. Limitations.
  417.  
  418.  
  419. THE PROGRAM IS PROVIDED TO YOU "AS IS", WITHOUT WARRANTY. THERE IS NO
  420. WARRANTY FOR THE PROGRAM, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
  421. LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  422. PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE ENTIRE
  423. RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD
  424. THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
  425. SERVICING, REPAIR OR CORRECTION.
  426.  
  427.  
  428. IF YOU DO NOT ACCEPT THIS LICENCE, YOU MUST DELETE THE PROGRAM, THE ARCHIVE
  429. AND ALL DATA OF THIS ARCHIVE FROM YOUR STORAGE SYSTEM. YOU ACCEPT THIS
  430. LICENCE BY USING OR REDISTRIBUTING THE PROGRAM.
  431.  
  432.  
  433.                                                         Thomas Richter
  434.  
  435. ------------------------------------------------------------------------------
  436.  
  437. Thomas Richter,
  438.         September 2000
  439.  
  440.  
  441. ============================= Archive contents =============================
  442.  
  443. Original  Packed Ratio    Date     Time    Name
  444. -------- ------- ----- --------- --------  -------------
  445.      456     271 40.5% 16-Sep-00 15:39:30 +DEV
  446.    16103    6448 59.9% 16-Sep-00 18:05:10 +Dev-Handler.readme
  447.      481     265 44.9% 09-Jul-00 14:22:50 +DEV.info
  448.     7392    4370 40.8% 16-Sep-00 15:39:18 +Device-Handler
  449.     1012     779 23.0% 22-Jul-00 20:25:22 +Extract
  450.      396     309 21.9% 16-Sep-00 17:24:52 +FixLongMult
  451.    14688    9310 36.6% 22-Jul-00 20:26:06 +spatch
  452.      144     135  6.2% 22-Jul-00 20:25:04 +statram.pch
  453. -------- ------- ----- --------- --------
  454.    40672   21887 46.1% 18-Sep-100 20:16:02   8 files
  455.